{
  LW VParm -- LightWave Time-Variant, Textured Parameters

  A variant parameter, or vparm, is a double-precision variable or 3-vector
  that can vary as a function of time. Vparms are used as containers for
  the values of XPanel controls that can be enveloped or textured
  (any control with "-env" in its type name).
  That's the rationale for the existence of vparms,
  but you're free to use them for other things as well.

  Based on lwvparm.h which is:
  Copyright 1999, NewTek, Inc.
}

{
  Copyright 2012, Jameel Halabi

  This unit is part of the BlaiseWave wrapper,
  which is licensed under the BSD 2-Clause license (see licenses/license.txt).
}
unit LW_VParm;

{$mode objfpc}{$H+}

interface

uses
  LW_Types ,
  LW_IO    ,
  LW_Envel ,
  LW_Txtr  ;

const
  LWVPARMFUNCS_GLOBAL = 'LWVParmFuncs 2' ;

  { LWVParm Envelope Types }
  LWVP_FLOAT                = $10 ;
  LWVP_PERCENT              = $20 ;
  LWVP_DIST                 = $30 ;
  LWVP_ANGLE                = $40 ;
  LWVP_COLOR                = $51 ;
  LWVP_COLORSIMPLE          = $61 ;
  LWVPF_VECTOR              = $01 ;
  LWVPF_VECTOR_DEFAULTNAMES = $00 ;
  LWVPF_VECTOR_NONAMES      = $02 ;
  LWVPF_VECTOR_PARMNAMES    = $04 ;

  { Texture Data Types }
  LWVPDT_NOTXTR       = -1 ;
  LWVPDT_VECTOR       =  0 ;
  LWVPDT_COLOR        =  1 ;
  LWVPDT_PERCENT      =  2 ;
  LWVPDT_SCALAR       =  3 ;
  LWVPDT_DISPLACEMENT =  4 ;

  { State Flags }
  LWVPSF_ENV = 1 shl 0 ; // create (set) or has (get) envelope
  LWVPSF_TEX = 1 shl 1 ; // create (set) or has (get) texture

  { VParm Event Notification
    Texture Event Codes:
      TXTRACK    - Generated as texture changes         (eventData == NULL)
      TXUPDATE   - Generated after texture has changed  (eventData == NULL)
      TXAUTOSIZE - Request for texture autosize         (eventData == bbox[3][2])
    Envelope Event Codes:
      ENVTRACK   - Generated as envelope changes        (eventData == NULL)
      ENVUPDATE  - Generated after envelope has changed (eventData == NULL)
    Envelope and Texture Instance Events:
      ENVNEW     - An envelope has been created         (eventData == NULL)
      ENVOLD     - The envelope is being destroyed      (eventData == NULL)
      TEXNEW     - A texture has been created           (eventData == NULL)
      TEXOLD     - The texture is being destroyed       (eventData == NULL)
      ENVRENAME  - The envelope group has been renamed  (eventData == NULL)       }
   // enum en_LWVP_EVENTCODES
   LWVPEC_TXTRACK     =  0 ;
   LWVPEC_TXUPDATE    =  1 ;
   LWVPEC_TXAUTOSIZE  =  2 ;
   LWVPEC_ENVTRACK    =  3 ;
   LWVPEC_ENVUPDATE   =  4 ;
   LWVPEC_ENVNEW      =  5 ;
   LWVPEC_ENVOLD      =  6 ;
   LWVPEC_TEXNEW      =  7 ;
   LWVPEC_TEXOLD      =  8 ;
   LWVPEC_ENVRENAME   =  9 ;


type
  PLWVParm = Pointer ;

  TLWVPEventFunc = function
                   (       VP         : PLWVParm     ;
                           UserData   : Pointer      ;
                           EventCode  : Integer      ; // Originally enum en_LWVP_EVENTCODES
                           EventData  : Pointer      ) : Integer ;
  { Time-Variant parameters are double precision vectors (3 element arrays)
    which may have a time-dependent nature - i.e., the value at time = 1.0
    is different at time = 2.0. Time-Variant parameters create and destroy
    LightWave envelopes as needed based on user interaction, application
    events, etc.

    ATTENTION: When using LWVParms with an LWXPanel, the VParm is "get-only"
               data. Never update the plugin's pointer during the XPanel
               "set". The plugin should always use the LWVParmID returned
               by the create method.

    API Methods
    -----------

    create:      Creates a time-variant parameter instance.
    destroy:     Releases resources used by instance.
    setup:       This MUST be called for each parameter created. The envelope
                 group ID is required. Any envelopes created for the
                 this parameter will belong to the specified group. A name
                 is also recommended for the parameter since this is what the
                 user may see when manipulating the envelope or texture.
    load:        Loads settings for a Time-Variant Parameter.
    save:        Saves settings for a Time-Variant Parameter.
    getVal:      Obtains the value of the parameter at a given time where
                 result is a 3 element array to be popuplated.
                 If a texture exists, the LWMicropolID should be non-NULL and
                 the return value is the texture's opacity.
                 If, however, the LWMicropolID is NULL, the texture's
                 contribution is ignored and only the parameter value
                 itself is returned.
    setVal:      Sets the value of the parameter where value is an array of
                 3 doubles. If the paramter is enveloped, setting the value
                 has no effect. The method returns the number of elements
                 processed (0, 1, or 3).
    getState:    Returns a bitflag value containing LWVPSF_* state flags
                 to indicate true if the parameter has an envelope and/or
                 texture, and may contain other state information in the future.
    setState:    This is the counterpart to the getState and using the
                 bitflags 'state' value to create or destroy the
                 parameter's envelope and or texture.
                 A false bit state indicates any existing envelope/texture
                 should be destroyed so it is recommended to use a getState
                 to obtain the current state information, make the necessary
                 adjustments, and then call setState.
                 Bit states of true will create an envelope or texture
                 (if one does not already exist) using the information
                 provided to the setup method.
    editEnv:     If an envelope exists for the paramenter, this will open
                 the envelope editor.
    editTex:     If a texture exists for the paramenter, this will open
                 the texture editor.
    initMP:      Utility method to initialize an LWMicropolID instance to
                 default settings.
    getEnv:      Populates 'envlist' with envelope instance(s) for the LWVParmID
                 If no envelope exists, the array elements will be NULL.
    getTex:      Returns the current texture instance for the LWVParmID        }

  PLWVParmFuncs = ^TLWVParmFuncs ;
  TLWVParmFuncs = record
    Create   : function
               (       EnvType     ,
                       TexType     : Integer        ) : PLWVParm ;
    Destroy  : procedure
               (       Parm        : PLWVParm );
    Setup    : procedure
               (       Parm        : PLWVParm       ;
                 const ChannelName : PChar          ;
                       Group		 : PLWChanGroup   ;
                       GC          : PLWTxtrContext ;
                       EventFunc   : TLWVPEventFunc ;
                 const PluginName  : PChar          ;
                       UserData    : Pointer        ) ;
    Copy     : function
               (       ParamTo     : PLWVParm       ;
                       ParamFrom   : PLWVParm       ) : PLWError ;
    Load     : function
               (       Parm        : PLWVParm       ;
                 const Load        : PLWLoadState   ) : PLWError ;
    Save     : function
               (       Parm        : PLWVParm       ;
                 const Save        : PLWSaveState   ) : PLWError ;
    GetVal   : function
               (       Parm        : PLWVParm       ;
                       Time 	   : TLWTime        ;
    		       MP          : PLWMicropol    ;
    		       Result      : PDouble        ) : Double;
    SetVal   : function
               (       Parm        : PLWVParm       ;
                       Value       : PDouble        ) : Integer ;
    GetState : function
               (       Parm        : PLWVParm       ) : Integer ;
    SetState : procedure
               (       Parm        : PLWVParm       ;
                       State       : Integer        ) ;
    EditEnv  : procedure
               (       Parm        : PLWVParm       ) ;
    EditTex  : procedure
               (       Parm        : PLWVParm       ) ;
    InitMP   : procedure
               (       MP          : PLWMicropol    ) ;
    GetEnv   : procedure
               (       Parm        : PLWVParm       ;
                       Envlist     : array {[0..2]} of PLWEnvelope ) ;
    GetTex   : function
               (       Parm        : PLWVParm       ) : PLWTexture;
  end;

implementation

end.

